Release 10.1A: OpenEdge Development:
ProDataSets

Duplicating ProDataSets with the CREATE-LIKE method

At times you need to create a new dynamic ProDataSet that has exactly the same structure as another ProDataSet, either static or dynamic. The CREATE-LIKE method does this for you, much as the same method name does for temp-tables, as shown:

Syntax

second-dataset-handle:CREATE-LIKE( { first-dataset-handle |                                      first-dataset-name-expr }                                      [ , prefix ] ).

The important parameters are:

second-dataset-handle is the handle of a dynamic ProDataSet object with no definition, which you want to have inherit the entire definition of the first-dataset.
prefix is an optional prefix string to be added to the beginning of the table names in the second-dataset. If you do not specify this, then the tables in the second-dataset have the same names as the tables in the first-dataset.

To use this method, you must first create a dynamic ProDataSet, and then use CREATE-LIKE to extract the definition of another, as in this sequence, where hDataSet is the handle of an existing ProDataSet:

DEFINE VARIABLE hDataSet2 AS HANDLE NO-UNDO. CREATE DATASET hDataSet2. hDataSet2:CREATE-LIKE(hDataSet).

The temp-table buffers in the second ProDataSet have the same name as those in the first. Because these are dynamic temp-tables and dynamic buffers, there is no name scoping conflict with the names of the original ProDataSet. You must, in any case, reference the temp-tables and buffers in hDataSet2 by their handles in order to identify them properly. However, if you wish to have distinct table names, you must supply the optional prefix argument.

You can use CREATE-LIKE any time you need a second dynamic ProDataSet within a procedure that has the same structure as another already defined or created. The ProDataSet structure, including temp-table and relation definitions, is copied to the second ProDataSet; the source ProDataSet’s data, however, is not copied.

If you need two static ProDataSets with the same structure within a single procedure, you need to define them individually using two different names, along with temp-tables with distinct names. Unlike the dynamic temp-tables in a ProDataSet you build using CREATE-LIKE, two static temp-tables scoped to the same procedure cannot have the same name. So, you could use a sequence of statements to create two equivalent static ProDataSets, as shown:

DEFINE TEMP-TABLE TableA FIELD KeyField1 AS INTEGER FIELD Field2 AS CHARACTER. DEFINE TEMP-TABLE TableB FIELD KeyField1 AS INTEGER FIELD Field3 AS CHARACTER. DEFINE DATASET DataSet1 FOR TableA, TableB DATA-RELATION Relation1 FOR TableA, TableB RELATION-FIELDS (KeyField1, KeyField1). DEFINE TEMP-TABLE TableA1 LIKE TableA. DEFINE TEMP-TABLE TableB1 LIKE TableB. DEFINE DATASET DataSet2 FOR TableA1, TableB1 DATA-RELATION Relation1 FOR TableA1, TableB1 RELATION-FIELDS (KeyField1, KeyField1).

An include file with an argument that adds a standard prefix or suffix to the temp-table and ProDataSet names could, of course, simplify the job of defining multiple sets of temp-tables and ProDataSets with equivalent structures, like those in the preceding example.

Keep in mind that these static ProDataSets and their temp-tables must have distinct names because they are top-level, unqualified objects that share the same name space within the procedure. The Data-Relations and Relation-Fields can have the same names in both ProDataSets because they are implicitly qualified within their definitions by the ProDataSet name, just as the temp-table fields are implicitly qualified by the temp-table name. Any reference to the fields within the procedure needs to explicitly qualify the names so that Progress knows which one you’re referring to. A relation can be accessed by name through its parent ProDataSet, as in DATASET DataSet1:GET-RELATION(“Relation1”) or in DATASET DataSet2:GET-RELATION(“Relation1”).

Alternatively, you can use a persistent procedure that defines a ProDataSet as a kind of factory for multiple instances of that ProDataSet. Each running instance of the procedure has its own ProDataSet, scoped to that procedure, each with its own data.

You typically use the CREATE-LIKE method to create a second ProDataSet for holding just the changes that have been made so that you can pass them to another procedure or another session for processing. This topic is discussed in later chapters along with the operation of before-tables where the original field values for changed rows are held. For now, note that if the original ProDataSet has defined before-tables, the CREATE-LIKE method creates a before-table for the tables in the new ProDataSet as well.

For cases where you want to copy the data in one ProDataSet to another ProDataSet, you can use the COPY-DATASET method, which is described in the "COPY-DATASET and COPY-TEMP-TABLE methods" section. COPY-DATASET also lets you copy the ProDataSet structure and definition as well, if the target is a dynamic ProDataSet handle with no structure. In this way, it lets you combine what the CREATE-LIKE method does with copying data in the same operation.